package com.ruoyi.system.mapper;

import java.util.List;
import com.ruoyi.system.domain.SuperBalance;
import com.ruoyi.system.domain.vo.BalanceVo;
import com.ruoyi.system.domain.vo.SuperBalanceVo;
import org.apache.ibatis.annotations.Param;

/**
 * 用户余额Mapper接口
 * 提供用户余额的数据库操作方法
 * 
 * @author ruoyi
 * @date 2025-08-14
 */
public interface SuperBalanceMapper 
{
    /**
     * 查询用户余额
     * 
     * @param id 用户余额主键
     * @return 用户余额
     */
    public SuperBalance selectSuperBalanceById(Long id);

    /**
     * 根据用户ID查询余额信息
     * 用于快速查询指定用户的余额信息，常用于用户登录后显示余额
     * 
     * @param userId 用户ID
     * @return 用户余额记录，如果用户没有余额记录则返回null
     */
    public SuperBalance selectSuperBalanceByUserId(Long userId);

    /**
     * 查询用户余额列表
     * 
     * @param superBalance 用户余额查询条件
     * @return 用户余额集合
     */
    public List<SuperBalance> selectSuperBalanceList(SuperBalance superBalance);

    /**
     * 查询用户余额列表（包含用户信息）
     * 通过关联查询获取余额信息和用户基本信息，用于管理后台显示
     * 包含的信息：用户昵称、用户账号、余额数量、创建时间、更新时间等
     * 
     * @param superBalance 用户余额查询条件
     * @return 包含用户信息的余额VO集合
     */
    public List<SuperBalanceVo> selectSuperBalanceVoList(SuperBalance superBalance);

    /**
     * 新增用户余额
     * 
     * @param superBalance 用户余额
     * @return 结果
     */
    public int insertSuperBalance(SuperBalance superBalance);

    /**
     * 修改用户余额
     * 
     * @param superBalance 用户余额
     * @return 结果
     */
    public int updateSuperBalance(SuperBalance superBalance);

    /**
     * 增加用户余额
     * 用于用户充值、退款等获得余额的业务场景
     * 实现逻辑：直接在现有余额基础上增加指定数量
     * 
     * @param userId 用户ID
     * @param balance 增加的余额数（必须为正数）
     * @return 影响的行数，1表示成功，0表示用户不存在余额记录
     */
    public int increaseUserBalance(@Param("userId") Long userId, @Param("balance") java.math.BigDecimal balance);

    /**
     * 减少用户余额
     * 用于用户消费、扣费等使用余额的业务场景
     * 实现逻辑：确保余额不会变为负数，如果余额不足则操作失败
     * 安全考虑：在SQL层面进行余额检查，防止余额变为负数
     * 
     * @param userId 用户ID
     * @param balance 减少的余额数（必须为正数）
     * @return 影响的行数，1表示成功，0表示余额不足或用户不存在
     */
    public int decreaseUserBalance(@Param("userId") Long userId, @Param("balance") java.math.BigDecimal balance);

    /**
     * 删除用户余额
     * 
     * @param id 用户余额主键
     * @return 结果
     */
    public int deleteSuperBalanceById(Long id);

    /**
     * 批量删除用户余额
     * 
     * @param ids 需要删除的用户余额主键集合
     * @return 结果
     */
    public int deleteSuperBalanceByIds(Long[] ids);
}
